/*
 * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */


package javax.naming.directory;

import java.util.Hashtable;
import java.util.Enumeration;

import javax.naming.NamingException;
import javax.naming.NamingEnumeration;

/**
 * This interface represents a collection of attributes.
 * <p>
 * In a directory, named objects can have associated with them
 * attributes.  The Attributes interface represents a collection of attributes.
 * For example, you can request from the directory the attributes
 * associated with an object.  Those attributes are returned in
 * an object that implements the Attributes interface.
 * <p>
 * Attributes in an object that implements the  Attributes interface are
 * unordered. The object can have zero or more attributes.
 * Attributes is either case-sensitive or case-insensitive (case-ignore).
 * This property is determined at the time the Attributes object is
 * created. (see BasicAttributes constructor for example).
 * In a case-insensitive Attributes, the case of its attribute identifiers
 * is ignored when searching for an attribute, or adding attributes.
 * In a case-sensitive Attributes, the case is significant.
 * <p>
 * Note that updates to Attributes (such as adding or removing an attribute)
 * do not affect the corresponding representation in the directory.
 * Updates to the directory can only be effected
 * using operations in the DirContext interface.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @see DirContext#getAttributes
 * @see DirContext#modifyAttributes
 * @see DirContext#bind
 * @see DirContext#rebind
 * @see DirContext#createSubcontext
 * @see DirContext#search
 * @see BasicAttributes
 * @since 1.3
 */

public interface Attributes extends Cloneable, java.io.Serializable {
    /**
     * Determines whether the attribute set ignores the case of
     * attribute identifiers when retrieving or adding attributes.
     *
     * @return true if case is ignored; false otherwise.
     */
    boolean isCaseIgnored();

    /**
     * Retrieves the number of attributes in the attribute set.
     *
     * @return The nonnegative number of attributes in this attribute set.
     */
    int size();

    /**
     * Retrieves the attribute with the given attribute id from the
     * attribute set.
     *
     * @param attrID The non-null id of the attribute to retrieve.
     *               If this attribute set ignores the character
     *               case of its attribute ids, the case of attrID
     *               is ignored.
     * @return The attribute identified by attrID; null if not found.
     * @see #put
     * @see #remove
     */
    Attribute get(String attrID);

    /**
     * Retrieves an enumeration of the attributes in the attribute set.
     * The effects of updates to this attribute set on this enumeration
     * are undefined.
     *
     * @return A non-null enumeration of the attributes in this attribute set.
     * Each element of the enumeration is of class <tt>Attribute</tt>.
     * If attribute set has zero attributes, an empty enumeration
     * is returned.
     */
    NamingEnumeration<? extends Attribute> getAll();

    /**
     * Retrieves an enumeration of the ids of the attributes in the
     * attribute set.
     * The effects of updates to this attribute set on this enumeration
     * are undefined.
     *
     * @return A non-null enumeration of the attributes' ids in
     * this attribute set. Each element of the enumeration is
     * of class String.
     * If attribute set has zero attributes, an empty enumeration
     * is returned.
     */
    NamingEnumeration<String> getIDs();

    /**
     * Adds a new attribute to the attribute set.
     *
     * @param attrID non-null The id of the attribute to add.
     *               If the attribute set ignores the character
     *               case of its attribute ids, the case of attrID
     *               is ignored.
     * @param val    The possibly null value of the attribute to add.
     *               If null, the attribute does not have any values.
     * @return The Attribute with attrID that was previous in this attribute set;
     * null if no such attribute existed.
     * @see #remove
     */
    Attribute put(String attrID, Object val);

    /**
     * Adds a new attribute to the attribute set.
     *
     * @param attr The non-null attribute to add.
     *             If the attribute set ignores the character
     *             case of its attribute ids, the case of
     *             attr's identifier is ignored.
     * @return The Attribute with the same ID as attr that was previous
     * in this attribute set;
     * null if no such attribute existed.
     * @see #remove
     */
    Attribute put(Attribute attr);

    /**
     * Removes the attribute with the attribute id 'attrID' from
     * the attribute set. If the attribute does not exist, ignore.
     *
     * @param attrID The non-null id of the attribute to remove.
     *               If the attribute set ignores the character
     *               case of its attribute ids, the case of
     *               attrID is ignored.
     * @return The Attribute with the same ID as attrID that was previous
     * in the attribute set;
     * null if no such attribute existed.
     */
    Attribute remove(String attrID);

    /**
     * Makes a copy of the attribute set.
     * The new set contains the same attributes as the original set:
     * the attributes are not themselves cloned.
     * Changes to the copy will not affect the original and vice versa.
     *
     * @return A non-null copy of this attribute set.
     */
    Object clone();

    /**
     * Use serialVersionUID from JNDI 1.1.1 for interoperability
     */
    // static final long serialVersionUID = -7247874645443605347L;
}
